<%@ Page Culture="auto" UICulture="auto" Title="MForm definition controls and MForm item controls"
    Language="C#" MasterPageFile="~/Site.Master" AutoEventWireup="true" CodeBehind="MFormItems.aspx.cs"
    Inherits="BM.Tools.WebControls.MForm.Example.Core.MFormItems" %>

<%@ Register Assembly="BM.Tools.WebControls.MForm" Namespace="BM.Tools.WebControls.MForm.Controls"
    TagPrefix="mf" %>
<%@ Register TagPrefix="mftitle" Namespace="BM.Tools.WebControls.MForm.Controls.Titles"
    Assembly="BM.Tools.WebControls.MForm" %>
<asp:Content ContentPlaceHolderID="Demonstration" runat="server">    
    <p>
        The following demonstration will show each of the existing MForm definition
        and item controls. There is a root control, which contains one leaf, one branch
        and one choice. The choice control on the other hand contains either a <code>FirstOption</code>
        branch or a <code>SecondOption</code> leaf:
    </p>
    <mf:RootValidator runat="server" ControlToValidate="Root1" />
    <mf:Root ID="Root1" runat="server">
        <Contents>
            <mf:Branch Name="SimpleTest" runat="server">
                <Contents>
                    <mf:Leaf Name="LeafElement" runat="server">
                    </mf:Leaf>
                    <mf:Branch Name="BranchElement" runat="server">
                        <Contents>
                            <mf:Leaf Name="leafAttribute" runat="server" DataType="PositiveInteger" LeafType="Attribute"
                                MinOccurs="0">
                            </mf:Leaf>
                        </Contents>
                    </mf:Branch>
                    <mf:Choice Name="Ch1" runat="server">
                        <Contents>
                            <mf:Leaf Name="SecondOption" runat="server">
                            </mf:Leaf>
                            <mf:Branch Name="FirstOption" runat="server">
                                <Contents>
                                    <mf:Leaf Name="OptionText" runat="server">
                                    </mf:Leaf>
                                    <mf:Leaf Name="OptionNumber" runat="server" DataType="Integer">
                                    </mf:Leaf>
                                </Contents>
                            </mf:Branch>
                        </Contents>
                    </mf:Choice>
                </Contents>
            </mf:Branch>
        </Contents>        
    </mf:Root>
</asp:Content>
<asp:Content ID="Content1" ContentPlaceHolderID="Description" runat="server">    
    <p>
        The MForm consists of several definition controls, that should be used together.
        These controls are:
    </p>
    <ul>
        <li>the <code>mf:Root</code> control</li>
        <li>the <code>mf:Branch</code> control</li>
        <li>the <code>mf:Choice</code> control</li>
        <li>the <code>mf:Leaf</code> control</li>
    </ul>
    <p>
        These controls reflect different XML data definitions.
    </p>
    <div class="Section" id="Offspring">
        <mftitle:TitleControl runat="server" Text="The Offspring base class" />
        <p>
            All of the described MForm definition controls inherit from one common class: <code>
                Offspring</code>. This class is responsible for all the common definition controls
            functionality:
        </p>
        <ul>
            <li>The <a href="#DisplayName"><code>DisplayName</code></a> property,</li>
            <li>The <a href="#MinOccurs_MaxOccurs"><code>MinOccurs</code> and <code>MaxOccurs</code></a>
                properties,</li>
            <li>The <a href="#Items"><code>Items</code></a> property,</li>
            <li>The <a href="#Mode"><code>Mode</code></a> property</li>
            <li>The <a href="#Name"><code>Name</code></a> property</li>
            <li>The <a href="#Navigator"><code>Navigator</code></a> property</li>
            <li>The <a href="#Ordinal"><code>Ordinal</code></a> property</li>
            <li>The <a href="#ParentItem_ParentBasis"><code>ParentItem</code> and <code>ParentBasis</code></a>
                properties</li>
            <li>The <a href="#Root_Property"><code>Root</code></a> property</li>
        </ul>
        <div class="Section" id="DisplayName">
            <mftitle:TitleControl ID="TitleControl1" runat="server" Text="The DisplayName property" />
            <p>
                All of these controls have the <code>DisplayName</code> property. This property
                can be used in different contexts (as a text label, a text in a tab, or a title
                text), which should describe the control.
            </p>
        </div>
        <div class="Section" id="MinOccurs_MaxOccurs">
            <mftitle:TitleControl ID="TitleControl2" runat="server" Text="The MinOccurs and MaxOccurs properties" />
            <p>
                All of these controls have properties <code>MinOccurs</code> and <code>MaxOccurs</code>,
                of which <code>MinOccurs</code> must be greater or equal zero, and <code>MaxOccurs</code>
                must be greater than zero. By default both of these properties are equal <code>1</code>.
            </p>
        </div>
        <div class="Section" id="Items">
            <mftitle:TitleControl ID="TitleControl3" runat="server" Text="The Items property" />
            <p>
                In the process of onpage control rendering, based on the <code>MinOccurs and MaxOccurs</code>
                properties and the input XML, each of the <em>MForm definition controls</em> generates
                an appropriate number of <em>MForm item controls</em>.These are:
            </p>
            <ul>
                <li>the <code>RootItem</code> control in the <code>Root</code> control,</li>
                <li>the <code>BranchItem</code> control in the <code>Branch</code> control,</li>
                <li>the <code>ChoiceItem</code> control in the <code>Choice</code> control,</li>
                <li>the <code>LeafItem</code> control in the <code>Leaf</code> control,</li>
            </ul>
            <p>
                These controls can be manipulated once thay are created, but they cannot be created
                by the user manually. This is similiar to the <code>Repeater</code> and <code>RepeaterItem</code>
                controls. The <em>item controls</em> are child controls of the <em>definition controls</em>
                and can be found inside the <code>Controls</code> property.
            </p>
            <p>
                Generally, the <em>definition controls</em> are specified in the .aspx definition
                but have no representation in the generated .html code. The <em>item controls</em>
                on the other hand are not defined directly in the .aspx (though they are defined
                indirectly, because changing the proprties of the <em>definition control</em> will
                influence the way the <em>item controls</em> are generated) but they are visible
                in the .html code.
            </p>
            <p>
                From the XML point of view, the <em>definition controls</em> keep information about
                the XML data definition which may repeat, whereas the <em>item controls</em> are
                bound to corporeal XML nodes.
            </p>
            <p>
                The <em>definition control</em> is aware of its child <em>item controls</em> through
                the <code>Items</code> property. The <em>item controls</em> are aware of its definition
                control through its <code>Basis</code> property.
            </p>
        </div>
        <div class="Section" id="Mode">
            <mftitle:TitleControl ID="TitleControl4" runat="server" Text="The Mode property" />
            <p>
                The <code>Mode</code> property is used to define the way MForm control should behave
                on the form. The default mode is the <code>Edit</code> mode in which adding, editing
                and removing are enabled. The other mode is the <code>View</code> mode, in which
                the control only shows the value. The <code>Mode</code> property is inherited in
                the MForm controls hierarchy, so if the <code>Root</code> control is in <code>View</code>
                mode, all of its MForm descendant controls will also be in <code>View</code> mode
                (unless the property is overriden by explicitly specifying <code>Edit</code> mode
                in the descendant control).
            </p>
            <p>
                The example of how <code>Mode</code> property works can be found on
                <asp:HyperLink ID="HyperLink1" runat="server" NavigateUrl="~/Core/Modes.aspx" Text="this page" />.
            </p>
        </div>
        <div class="Section" id="Name">
            <mftitle:TitleControl ID="TitleControl5" runat="server" Text="The Name property" />
            <p>
                The <code>Name</code> property is the string representation of the offspring control's
                qualified name. Some offsprings, like <code>Branch</code> and <code>Leaf</code>
                represent definitions of XML nodes. For those controls, the <code>Name</code> property
                is very important as it will denote which XML node will be read into the control,
                as well as what will be the XML output. For other controls, like <code>Root</code>
                and <code>Choice</code> this property does not affect the XML input and output.
                However it is still very important, as this property is used when using the
                <asp:HyperLink ID="HyperLink2" runat="server" NavigateUrl="~/Core/Navigation.aspx"
                    Text="xpath-like MForm control tree query language" />.
            </p>
            <p>
                The prefixes in the qualified name are resolved through the Root's <code>Manager</code>
                property, which is a XmlNamespaceManager created from UriMappings definitions.
            </p>
            <div class="Remark">
                <p>
                    If the <code>Name</code> property is not preceded by any prefix, the name is considered
                    to be in a default namespace. The default namespace in <code>UriMappings</code>
                    is defined by the UriMapping, whose <code>Prefix</code> property equals an empty
                    string.</p>
            </div>
            <dl class="Example">
                <dd>
                    Let's assume such Root's <code>UriMappings</code> property:
                    <pre>
&lt;UriMappings&gt;
    &lt;mf:UriMapping Prefix="" Namespace="urn:defaultNamespace" /&gt;
    &lt;mf:UriMapping Prefix="x" Namespace="urn:mysterious.x.namespace" /&gt;
&lt;/UriMappings&gt;
</pre>
                </dd>
                <dt>Example:</dt>
                <dd>
                    A branch control that has the Name property set to <code>SampleElement</code> reflects
                    a definition of XML elements whose local name is "<span class="namespace">SampleElement</span>"
                    and namespace uri is "<span class="namespace">urn:defaultNamespace</span>"</dd>
                <dt>Example 2:</dt>
                <dd>
                    A leaf control that has the Name property set to <code>x:OtherElement</code> reflects
                    a definition of XML elements whose local name is "<span class="namespace">OtherElement</span>"
                    and namespace uri is "<span class="namespace">urn:mysterious.x.namespace</span>"</dd>
            </dl>
        </div>
        <div class="Section" id="Navigator">
            <mftitle:TitleControl ID="TitleControl6" runat="server" Text="The Navigator property" />
            <p>
                When the MForm controls tree is fed with an input XML, this XML document nodes are
                recursively matched with controls. If the match is found, the matched XML node becomes
                control's data source. The <code>Navigator</code> property is a <code>XPathNavigator</code>
                object created from this dta source.
            </p>
        </div>
        <div class="Section" id="Ordinal">
            <mftitle:TitleControl ID="TitleControl7" runat="server" Text="The Ordinal property" />
            <p>
                XML is a tree structure in which order of nodes matters. To make MForm display less
                coupled with the XML definition, the <code>Ordinal</code> property was introduced.
                With the use of the <code>Ordinal</code> property, the order in which sibling MForm
                controls are placed is irrelevant. The corresponding XML nodes will be ascendingly
                sorted with the use of the property.
            </p>
        </div>
        <div class="Section" id="ParentItem_ParentBasis">
            <mftitle:TitleControl ID="TitleControl8" runat="server" Text="The ParentItem and ParentBasis properties" />
            <p>
            </p>
        </div>
        <div class="Section" id="Root_Property">
            <mftitle:TitleControl ID="TitleControl9" runat="server" Text="The Root property" />
            <p>
            </p>
        </div>
    </div>
    <div class="Section" id="OffspringsOwner">
        <mftitle:TitleControl runat="server" Text="The OffspringsOwner base class" />
        <p>
            All controls except the <code>Leaf</code> control inherit from the <code>OffspringsOwner</code>
            class, meaning that they may contain other MForm definition controls inside. These
            MForm definition controls as well as other controls may be defined in the <a href="#Contents">
                <code>Contents</code></a> property.
        </p>
        <div class="Section" id="Contents">
            <mftitle:TitleControl ID="TitleControl10" runat="server" Text="The Contents property" />
            <p>
                The <code>Contents</code> property is a template that may consist of any controls,
                particularly it my contain other MForm definition controls as its descendants. All
                of these controls are instantiated in the child items of the offspring owner control.
            </p>
            <dl class="Example">
                <dt>Example:</dt>
                <dd>
                    <p>
                        A <code>Branch</code> control with the <code>MinOccurs</code> property equal 3,
                        having <code>Contents</code> property equal</p>
                    <pre>
&lt;asp:Label runat="server" Text="SomeText" /&gt;
&lt;mf:Branch runat="server" Name="InnerBranch" &gt;
    ...
&lt;mf:Branch /&gt;
</pre>
                    <p>
                        will render at least 3 <code>BranchItem</code> controls. Each of these <code>BranchItem</code>
                        controls will have the <code>SomeText</code> label and the <code>InnerBranch</code>
                        branch controls instantiated inside itself. Effectively, 3 <code>SomeText</code>
                        labels and 3 <code>InnerBranch</code> branches will be instantiated.
                    </p>
                    <p>
                        Again, if the <code>InnerBranch</code> branch definition control had <code>MinOccurs</code>
                        property equal more than 1, its <code>Contents</code> property would be instantiated
                        multiple times inside its <code>BranchItem</code> child items.
                    </p>
                </dd>
            </dl>
        </div>
    </div>
    <div class="Section" id="Root">
        <mftitle:TitleControl ID="TitleControl11" runat="server" Text="The <code>mf:Root</code> control" />
        <p>
            The root control reflects the xml document root.
        </p>
        <p>
            The <code>mf:Root</code> control needs to be used as the root of conrols tree. Using
            the <code>mf:Root</code> control inside the tree of MForm controls will result in
            starting a new inner MForm control and is generally considered inappropriate.
        </p>
        <div class="Section" id="Root_InputOutput">
            <mftitle:TitleControl ID="TitleControl12" runat="server" Text="Input and output" />
            <p>
                The root control is responsible for data input/output. The input to the Root can
                be any object of type <code>IXPathNavigable</code>, and can be provided by specifying
                the <code>DataSource</code> property, or by specifying the <code>DataSourceId</code>
                property.
            </p>
            <p>
                The <code>DataSourceId</code> property of type string should denote a DataSourceObject
                - currently only <code>XmlDataSource</code> is supported.
            </p>
            <div class="Remark">
                <p>
                    If both <code>DataSource</code> and <code>DataSourceId</code> properties are specified,
                    the <code>DataSource</code> property takes precendence.</p>
            </div>
            <p>
                The output of the Root control can be found under the <code>OutputXml</code> property
                - it is a generated <code>XmlDocument</code> object.
            </p>
            <p>
                In case the input xml did not exactly match the structure of the MForm, and the
                output ought to contain the not matching nodes, the property <code>OutputXmlWithLeftNodes</code>
                can be used.
            </p>
        </div>
        <div class="Section" id="Root_Contents">
            <mftitle:TitleControl ID="TitleControl13" runat="server" Text="Contents" />
            <p>
                The <code>mf:Root</code> control, as other <code>OffspringsOwner</code> controls,
                has a <code>Contents</code> property. The <code>Contents</code> property may contain
                any inner controls, particularly it may contain other MForm definition controls.
            </p>
            <div class="Remark">
                <p>
                    Because the root control reflects the xml document root, it <span class="Important">
                        should contain exactly one mform child item</span>. In case of at least one
                    of the following:</p>
                <ul>
                    <li>the root has occurence higher than one</li>
                    <li>the root has more than one mform definition control</li>
                    <li>the definition control, which is a child of the root has occurence higher than one</li>
                </ul>
                <p>
                    no exception will be thrown, but the output xml will reflect only the data from
                    the first child item. This behavior can be best understood, if you consider adding
                    more than one element to the XmlDocument - it would inevitably result in an exception.</p>
            </div>
        </div>
        <div class="Section" id="Root_PrefixNs">
            <mftitle:TitleControl ID="TitleControl14" runat="server" Text="Prefix-namespace mappings" />
            <p>
                To be able to use the same namespace manager for the whole MForm tree, and to be
                able to define this manager in .aspx, the <code>UriMappings</code> property has
                been defined for the Root control. The UriMappings is a list of <code>UriMapping</code>
                controls.
            </p>
            <p>
                Each <code>UriMapping</code> control contains two properties:
            </p>
            <ul>
                <li><em>Prefix</em>: the prefix string,</li>
                <li><em>Namespace</em>: the namespace uri string,</li>
            </ul>
        </div>
        <div class="Section" id="Root_Navigation">
            <mftitle:TitleControl ID="TitleControl15" runat="server" Text="MForm tree navigation" />
            <p>
                To make it easier to navigate across the MForm controls, the methods <code>Select</code>
                and <code>SelectSingle</code> are available for the Root control. These methods
                expect an XPath-like expression to find instances of MForm items.
            </p>
        </div>
    </div>
    <div class="Section" id="Branch">
        <mftitle:TitleControl ID="TitleControl16" runat="server" Text="The <code>mf:Branch</code> control" />
        <p>
            The branch control reflects a definition of XML element with attribute nodes or
            with other children elements inside.
        </p>
        <div class="Section" id="Branch_Name">
            <mftitle:TitleControl ID="TitleControl17" runat="server" Text="The Name" />
            <p>
                The <code>Name</code> property of the Branch control reflects the qualified name
                of the XML element.
            </p>
        </div>
        <div class="Section" id="Branch_Contents">
            <mftitle:TitleControl ID="TitleControl18" runat="server" Text="Contents" />
            <p>
                The <code>mf:Branch</code> control, as other <code>OffspringsOwner</code> controls,
                has a <code>Contents</code> property. The <code>Contents</code> property may contain
                any inner controls, particularly it may contain other MForm definition controls.
            </p>
            <p>
                There are no restrictions on the contents of the <code>Branch</code> control.
            </p>
        </div>
    </div>
    <div class="Section" id="Choice">
        <mftitle:TitleControl ID="TitleControl19" runat="server" Text="The <code>mf:Choice</code> control" />
        <p>
            The choice control reflects the group of xml nodes of which only one can be used.
        </p>
        <div class="Remark">
            <p>
                When generated from XML Schema, the <code>Choice</code> control will appear whereever
                <code>xsd:choice</code> element was specified or where there was a definition of
                an abstract element with other elements having <code>substGroup</code> specified.</p>
        </div>
        <div class="Section" id="Choice_Name">
            <mftitle:TitleControl ID="TitleControl20" runat="server" Text="The Name" />
            <p>
                The <code>Name</code> property of the Choice control has no particular meaning for
                the reflected XML data representation. However this name may be used when selecting
                MForm items using the xpath-like language so you should keep it meaningful.
            </p>
        </div>
        <div class="Section" id="Choice_Contents">
            <mftitle:TitleControl ID="TitleControl21" runat="server" Text="Contents" />
            <p>
                The <code>mf:Choice</code> control, as other <code>OffspringsOwner</code> controls,
                has a <code>Contents</code> property. The <code>Contents</code> property may contain
                any inner controls, particularly it may contain other MForm definition controls.
            </p>
            <p>
                Each of the mform definition controls inside the choice contents is one of the choice
                options. All non-mform controls inside the Choice control will be rendered as they
                are.
            </p>
        </div>
    </div>
    <div class="Section" id="Leaf">
        <mftitle:TitleControl ID="TitleControl22" runat="server" Text="The <code>mf:Leaf</code> control" />
        <p>
            The leaf control reflects a xml attribute or a xml element which contains only a
            text node.
        </p>
        <div class="Section" id="Leaf_Name">
            <mftitle:TitleControl ID="TitleControl23" runat="server" Text="The Name" />
            <p>
                The <code>Name</code> property of the Leaf control reflects the qualified name of
                either the XML element or the name of the XML attribute. It works the same way as
                in the Branch control.
            </p>
        </div>
        <div class="Section" id="Leaf_LeafType">
            <mftitle:TitleControl ID="TitleControl24" runat="server" Text="The leaf type" />
            <p>
                To examine, whether the Leaf control reflects the element or the attribute, the
                <code>LeafType</code> property exists.
            </p>
        </div>
        <div class="Section" id="Leaf_Label">
            <mftitle:TitleControl ID="TitleControl25" runat="server" Text="The label" />
            <p>
                By default, each leaf item control contains a label, and the text for this label
                is taken from the <code>DisplayName</code>. The template for this label can be specified
                within the <code>Label</code> property in the <code>Leaf</code> control.
            </p>
        </div>
        <div class="Section" id="Leaf_ValueHandler">
            <mftitle:TitleControl ID="TitleControl26" runat="server" Text="The value handler" />
            <p>
                Each leaf item control contains a value handler, which is used for manipulation
                on the text of the leaf node. Each value handler is an adapter of a control it contains
                inside. The default value handler is <code>TextBoxValueHandler</code>
            </p>
        </div>
    </div>
</asp:Content>
